4  Software Design Description

4.1 Overall Description

4.1.1 Assumptions

• The target platform is a Docker-compatible operating system (Preferably Linux).
• The target web browser is Google Chrome.
• All products are run and operated in the same machine (Monolithic architecture).
• Only administrators can access the running system. Other users can only access the system through the frontend server.
• The blockchain is a private blockchain.
• The blockchain is an optional feature that can be turned on or off.
• The database is a H2 database.
• The mode of the database can be in-memory (for testing), file or remote (for production).

4.1.2 Design Constraints

• The backend system is a REST API server.
• The backend system is a Java application.
• The blockchain is a Hyperledger Fabric blockchain.
• There should be an option to turn on or off the blockchain. If the blockchain is turned off, the backend system should still work as a normal REST API server with a local database.

4.1.3 Technology Suggestion

• The endpoints of the backend system can be exposed so that a node browser can be developed to search & access the endpoints and get the necessary information.

4.2 System Architecture Design

4.2.1 Overall Architecture

Figure 4.1: Overall Architecture

4.2.2 System Architecture

Figure 4.2: System Architecture

4.2.3 Package Diagram

Figure 4.3: Package Diagram of Request Server

Table 4.1: Package Detail of the Request Server

Package Name	Description
root	Main classes
api	The abstract classes & interfaces
entity	The entities of the database
handler	The handlers of the endpoints of the REST API server
internal	Internal classes used by other packages
internal/student	The instances of the Student Updater
model	The input / output objects
model/input	The input objects for the handlers
model/output	The output objects returned from the handlers
model/fabric	The models used internally by the student updater

4.3 System Detailed Design

4.3.1 Class Specification

Figure 4.4: Class Diagram of the Request Server

4.3.1.1 Account

Table 4.2: Fields of Account

Field Name	Type	Description
id	long	The account id
username	String	The username
hashedPassword	String	The hashed password
salt	String	The salt of the password
role	String	The role of the account
createdAt	Date	The date when the account was created
classrooms	List ClassTeacher	The list of references to the classrooms that the account participates if its role is Teacher
recordEntries	List RecordEntry	The list of record entries related to the subjects that the account is teaching if its role is Teacher
requestedRecordEntries	List RecordEntry	The list of verified record entries that the account requested to changes
approvedRecordEntries	List RecordEntry	The list of verified record entries that the account accepted
pendingRecordEntries	List PendingRecordEntry	The list of pending record entries related to the subjects that the account is teaching if its role is Teacher
requestedPendingRecordEntries	List PendingRecordEntry	The list of pending record entries that the account requested to changes
homeClassrooms	List Classroom	The list of classrooms the the account is a homeroom teacher at

4.3.1.2 Profile

Table 4.3: Fields of Profile

Field Name	Type	Description
id	long	The account id
account	Account	The reference to the Account object
firstName	String	The first name
lastName	String	The last name
male	boolean	Is the person male? false if she is a female
avatar	String	The link to the avatar image
birthDate	Date	The date of the birthday
address	String	The address
phone	String	The phone number
email	String	The email
updated	boolean	The flag indicates that the profile requires synchronization with the Chain Node

4.3.1.3 Student

Table 4.4: Fields of Student

Field Name	Type	Description
id	long	The account id
account	Account	The reference to the Account object
ethnic	String	The ethnic of the student
fatherName	String	The name of the father of the student
fatherJob	String	The job of the father of the student
motherName	String	The name of the mother of the student
motherJob	String	The job of the mother of the student
guardianName	String	The name of the guardian of the student
guardianJob	String	The job of the guardian of the student
homeTown	String	The home town of the student
classrooms	List ClassStudent	The list of references to the classrooms that the student participates
records	List Record	The list of records related to the classrooms that the student participates
updaterKey	List UpdaterKey	The list of updater keys of the student. Used to allow outsiders to get information of the student.

4.3.1.4 Classroom

Table 4.5: Fields of Classroom

Field Name	Type	Description
id	long	The classroom id
name	String	The name of the classroom
grade	int	The grade of the classroom
year	int	The year of the classroom
homeroomTeacher	Account	The reference to the homeroom teacher of the classroom
students	List ClassStudent	The list of references to the students that participate in the classroom
teachers	List ClassTeacher	The list of references to the teachers that participate in the classroom
records	List Record	The list of records related to the classroom

4.3.1.5 ClassStudent

Table 4.6: Fields of ClassStudent

Field Name	Type	Description
id	long	The id of the reference
classroom	Classroom	The reference to the classroom
student	Student	The reference to the student

4.3.1.6 ClassTeacher

Table 4.7: Fields of ClassTeacher

Field Name	Type	Description
id	long	The id of the reference
classroom	Classroom	The reference to the classroom
teacher	Account	The reference to the teacher
subjectId	long	The id of the subject that the teacher teaches

4.3.1.7 Record

Table 4.8: Fields of Record

Field Name	Type	Description
id	long	The record id
classroom	Classroom	The reference to the classroom
student	Student	The reference to the student
recordEntry	List RecordEntry	The list of verified record entries related to the record
pendingRecordEntry	List PendingRecordEntry	The list of pending record entries related to the record

4.3.1.8 RecordEntry

Table 4.9: Fields of RecordEntry

Field Name	Type	Description
id	long	The record entry id
subjectId	long	The id of the subject that the record entry is related to
firstHalfScore	int	The score of the first semester of the subject
secondHalfScore	int	The score of the second semester of the subject
finalScore	int	The final score of the subject
requestDate	Date	The date when the record entry was requested
approvalDate	Date	The date when the record entry was approved
updateComplete	boolean	The flag indicates that the record entry was updated to the Chain Node
teacher	Account	The reference to the teacher that teaches the subject
requester	Account	The reference to the account that requested the record entry
approver	Account	The reference to the account that approved the record entry
record	Record	The reference to the record that the record entry is related to

4.3.1.9 PendingRecordEntry

Table 4.10: Fields of PendingRecordEntry

Field Name	Type	Description
id	long	The pending record entry id
subjectId	long	The id of the subject that the pending record entry is related to
firstHalfScore	int	The score of the first semester of the subject
secondHalfScore	int	The score of the second semester of the subject
finalScore	int	The final score of the subject
requestDate	Date	The date when the pending record entry was requested
teacher	Account	The reference to the teacher that teaches the subject
requester	Account	The reference to the account that requested the pending record entry
record	Record	The reference to the record that the pending record entry is related to

4.3.1.10 UpdaterKey

Table 4.11: Fields of UpdaterKey

Field Name	Type	Description
id	String	The unique key
student	Student	The reference to the student that the key is related to

4.3.1.11 StatisticKey

Table 4.12: Fields of StatisticKey

Field Name	Type	Description
id	String	The unique key
year	int	The year that the key is referred to
grade	int	The grade that the key is referred to

4.3.2 Sequence Diagram

4.3.2.1 Create Account

Figure 4.5: Sequence Diagram to Create Account

4.3.2.2 Get Account

Figure 4.6: Sequence Diagram to Get Account

4.3.2.3 Get Account List

Figure 4.7: Sequence Diagram to Get Account List

4.3.2.4 Login

Figure 4.8: Sequence Diagram to Login

4.3.2.5 Update Account Password

Figure 4.9: Sequence Diagram to Update Account Password

4.3.2.6 Update Account Profile

Figure 4.10: Sequence Diagram to Update Account Profile

4.3.2.7 Create Classroom

Figure 4.11: Sequence Diagram to Create Classroom

4.3.2.8 Add Students To Classroom

Figure 4.12: Sequence Diagram to Add Students To Classroom

4.3.2.9 Remove Students From Classroom

Figure 4.13: Sequence Diagram to Remove Students From Classroom

4.3.2.10 Add Teachers To Classroom

Figure 4.14: Sequence Diagram to Add Teachers To Classroom

4.3.2.11 Remove Teachers From Classroom

Figure 4.15: Sequence Diagram to Remove Teachers From Classroom

4.3.2.12 Update Classroom

Figure 4.16: Sequence Diagram to Update Classroom

4.3.2.13 Get Classroom

Figure 4.17: Sequence Diagram to Get Classroom

4.3.2.14 Get Classroom List

Figure 4.18: Sequence Diagram to Get Classroom List

4.3.2.15 Get Students In Classroom

Figure 4.19: Sequence Diagram to Get Students In Classroom

4.3.2.16 Get Teachers In Classroom

Figure 4.20: Sequence Diagram to Get Teachers In Classroom

4.3.2.17 Get Student Record

4.3.2.18 Get Student Record List

4.3.2.19 Update Student Record

4.3.2.20 Create Request To Update Student Record

4.3.2.21 Get Pending Record Requests

4.3.2.22 Approve Pending Record Request

4.3.2.23 Upload Record To Chain Node

4.3.2.24 Create Statistic Key

4.3.2.25 Get Statistic Key List

4.3.2.26 Delete Statistic Key

4.3.2.27 Get Statistic Data

4.3.2.28 Create Student Key

4.3.2.29 Get Student Key List

4.3.2.30 Delete Student Key

4.3.2.31 Get Student Data From Key

4.3.2.32 Upload Legacy Student Record

4.4 Data & Database Design

4.4.1 Database Design

Figure 4.21: Database Design of the Request Server

4.4.1.1 Account

Table 4.13: Attributes of the Account table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
USERNAME	character varying	255	x	x
HASHEDPASSWORD	character varying	255		x
SALT	character varying	255		x
ROLE	character varying	255		x
CREATEDAT	timestamp			x

4.4.1.2 Profile

Table 4.14: Attributes of the Profile table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ACCOUNT_ID	bigint		x	x	PK, FK
ADDRESS	character varying	255		x
AVATAR	character varying	255		x
BIRTHDATE	timestamp			x
EMAIL	character varying	255		x
FIRSTNAME	character varying	255		x
LASTNAME	character varying	255		x
MALE	boolean			x
PHONE	character varying	255		x
UPDATED	boolean			x		Used internally by student updater

4.4.1.3 Student

Table 4.15: Attributes of the Student table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ACCOUNT_ID	bigint		x	x	PK, FK
ETHNIC	character varying	255		x
FATHERJOB	character varying	255		x
FATHERNAME	character varying	255		x
GUARDIANJOB	character varying	255		x
GUARDIANNAME	character varying	255		x
HOMETOWN	character varying	255		x
MOTHERJOB	character varying	255		x
MOTHERNAME	character varying	255		x

4.4.1.4 Classroom

Table 4.16: Attributes of the Classroom table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
NAME	character varying	255		x
GRADE	character varying	255		x
HOMEROOMTEACHER_ID	bigint			x	FK
START_YEAR	integer			x

4.4.1.5 Class Student

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
CLASSROOM_ID	bigint			x	FK
STUDENT_ID	bigint			x	FK

4.4.1.6 Class Teacher

Table 4.17: Attributes of the Class Teacher table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
CLASSROOM_ID	bigint			x	FK
TEACHER_ID	bigint			x	FK
SUBJECTID	bigint			x		Defined in the system’s config

4.4.1.7 Record

Table 4.18: Attributes of the Record table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
CLASSROOM_ID	bigint			x	FK
STUDENT_ACCOUNT_ID	bigint			x	FK

4.4.1.8 Record Entry

Table 4.19: Attributes of the Record Entry table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
RECORD_ID	bigint			x	FK
REQUESTER_ID	bigint				FK
TEACHER_ID	bigint				FK
APPROVER_ID	bigint				FK
APPROVALDATE	timestamp			x
REQUESTDATE	timestamp			x
FIRSTHALFSCORE	double precision			x
SECONDHALFSCORE	double precision			x
FINALSCORE	double precision			x
SUBJECTID	bigint			x		Defined in the system’s config
UPDATECOMPLETE	boolean			x		Used internally by student updater

4.4.1.9 Pending Record Entry

Table 4.20: Attributes of the Pending Record Entry table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	bigint		x	x	PK
RECORD_ID	bigint			x	FK
REQUESTER_ID	bigint			x	FK
TEACHER_ID	bigint			x	FK
REQUESTDATE	timestamp			x
FIRSTHALFSCORE	double precision			x
SECONDHALFSCORE	double precision			x
FINALSCORE	double precision			x
SUBJECTID	bigint			x		Defined in the system’s config

4.4.1.10 Updater Key

Table 4.21: Attributes of the Updater Key table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	character varying	255	x	x	PK
STUDENT_ACCOUNT_ID	bigint			x	FK

4.4.1.11 Statistic Key

Table 4.22: Attributes of the Statistic Key table

Field Name	Type	Size	Unique	Not Null	Flag	Notes
ID	character varying	255	x	x	PK
GRADE	integer			x
START_YEAR	integer			x

4.4.2 Data File Design

Table 4.23: Data File Structure

File Name	Type	Notes
db	Folder	The folder of The H2 Database files
updater	Folder	Contains the data files of the local student updater